home *** CD-ROM | disk | FTP | other *** search
/ Aminet 28 / Aminet 28 (1998)(GTI - Schatztruhe)[!][Dec 1998].iso / Aminet / dev / amos / intuiextend16.lha / bonus / easylife / demos / VarChecker.doc < prev    next >
Text File  |  1992-02-26  |  11KB  |  319 lines
  1.  
  2.                  AMOS Pro Variable Checker Version 1.00 
  3.                  ======================================
  4.  
  5.                     By Paul Hickman (ph@doc.ic.ac.uk)
  6.                     =================================
  7.  
  8.  
  9.  
  10. OVERVIEW
  11. ========
  12.  
  13. The variable checker is an accessory program which scans another
  14. programs source from the AMOS Pro editor, and reports possible
  15. errors in the use of variable names that AMOS Pro does not normally
  16. detect. This help debug programs, optimises them by allowing to remove
  17. assignments that are unneccessary, and leads to better programming
  18. practice.
  19.  
  20.  
  21. REQUIREMENTS
  22. ============
  23.  
  24. Any version of AMOS Pro. Enough memory to load the accessory,
  25. and the program to check simultaneously.
  26.  
  27.  
  28. DISTRIBUTION
  29. ============
  30.  
  31. This progam may be freely distributed, as long as no profit is
  32. made from doing so. It may not be put on a disk together with 
  33. programs for which a profit is made from distributing them.
  34.  
  35.  
  36.  
  37. GLOSSARY
  38. ========
  39.  
  40. Reference / Referal
  41. -------------------
  42.  
  43.     A Reference to a variable is where the variable is used in the
  44.     arguments of an AMOS function, or command where it's value is
  45.     read, and not altered. The following are all references to VAR:
  46.  
  47.     Print "The Answer is:";VAR
  48.     _CALL_THE_PROCUEDRE[1,"Fred",VAR,False]
  49.     X=4+VAR*2
  50.     End Proc[VAR]
  51.  
  52. Declaration
  53. -----------
  54.  
  55.     The declaration of a variable notifies AMOS that it exists. All
  56.     Definitions/Assignments are also declarations, as are variable
  57.     names in Shared & Global statements.
  58.  
  59.  
  60. Definition / Assignments
  61. ------------------------
  62.  
  63.     The definition / assignment of a variable is where the value of
  64.     the variable is set by an AMOS command, or the '=' operation,
  65.     without refering to VAR. The following are all definitions of VAR:
  66.  
  67.     VAR=4    
  68.     Read VAR
  69.     Input "Enter Value Of Var:";VAR
  70.     Input #1,VAR;
  71.     Line Input #1,VAR
  72.     Procedure A_PROCEDURE[VAR]
  73.  
  74.  
  75.     These are not definitions of VAR, as they always require VAR to
  76.     be set (Or implicitly take it to be 0 if it isn't)
  77.  
  78.     VAR=VAR+4            (Also a reference to VAR)
  79.     Add VAR,6
  80.     Dec VAR
  81.  
  82.  
  83.  
  84. USAGE
  85. =====
  86.  
  87. Load the Variable Checker into AMOS Pro as an accessory program,
  88. then load the souce you wish to check into the editor,and test it.
  89. With the source window active, run the variable checker accessory.
  90.  
  91. Firstly all procedures are unfolded, and the entire program is scanned 
  92. for all shared variables, so that they to not show up as undefined if 
  93. used in the main program before they are set. Then program is checked 
  94. top to bottom, and the following errors are detected on the line they
  95. occur:
  96.  
  97.  
  98.     Variables that are made Global after they have already been used.
  99.     -----------------------------------------------------------------
  100.     
  101.         Doing this can confuse the AMOS compiler, and it is generally
  102.         bad programming practice. Move all Global statement to the top
  103.     of your program.
  104.  
  105.  
  106.    Global Variables that are shared in some procedures
  107.    ---------------------------------------------------
  108.  
  109.        Making a global variable shared is a pointless exercise. Remove
  110.        the shared statement from the offending procedure.
  111.  
  112.        NOTE: Even if a global variable is shared in several procedures, 
  113.        this error will only be reported once.
  114.  
  115.  
  116.    Undefined Local Variables
  117.    -------------------------
  118.  
  119.         An undefined local variable is a variable which is not global,
  120.         or shared, and is refered to in the program, before
  121.         it has been defined (See Glossary)
  122.  
  123.         This error occurs if the variable is used above the point in the
  124.         program at which it is defined. This should not be a problem with
  125.         well structred programs, but those which use Goto/Gosub may find
  126.         that frequently a variable is defined after the point it is used.
  127.  
  128.         NOTES: No error will occur at this stage, if the variable is a
  129.            shared or global variable. They are only reported if they
  130.            are never defined anywhere. This also applies to shared
  131.            variables when they are used in the main program.
  132.  
  133.  
  134.         This is the most frequently occuring error, and can be the most
  135.     dangerous. If possible (practical -it's always possible), you 
  136.     should never asssume that a variable is uninitialised, and
  137.     therefore 0, as:
  138.  
  139.     - You might modify the program to use it later, and it will then
  140.       stop working.
  141.  
  142.     - The program will throw out loads of 'Local Varaible Undefined'
  143.       errors, obscuring the times when you have actually mis-spelled
  144.       a variable name, which is the case when this error being in your
  145.       program makes it incorrect, and may make it crash.             
  146.  
  147.     NOTE: This error will only occur the first time each undeclared
  148.               variable is used in each procedure/the main program.
  149.  
  150.  
  151.  
  152. When an 'End Proc' statement is encountered, in the program, the procedure
  153. is then checked for these errors:
  154.  
  155.    Unreferenced Local Variables
  156.    ----------------------------
  157.  
  158.     This is the opposite of the 'Undefined Local Variable' - A value
  159.     has been assigned to a variable, but the variable is never refered 
  160.     to in the arguments of a function / command. This error only occurs
  161.     within procedures during this stage of checking.
  162.  
  163.     NOTE: Sometimes an unreferenced variable is not an error e.g.
  164.           A=Dialog Box(A$,0,B$). If you don't care what the dialog
  165.           box returns, but just want to display it, A will be
  166.           unreferenced. In such cases, A should be replaced with NULL.
  167.           This program does not produce errors if NULL is unreferenced.
  168.           By forcing you to use NULL, this shows other people reading 
  169.           the code that it is not used. (NULL# & NULL$ can be used
  170.           when appropriate)
  171.  
  172.     NOTE: This error will not occur for variables that are defined as
  173.               loop counters in For...Next loops.
  174.  
  175.  
  176.  
  177.    Unused Shared Variables
  178.    -----------------------
  179.  
  180.     This error occurs if a variable is made shared in a procedure, but
  181.     is then not used in that procedure - I.E. it is not assigned to,
  182.     or refered to.
  183.  
  184.  
  185.  
  186. Finally, at the end of the source, the program checks for these errors.
  187. As each occurs, the cursor is moved to the line on which the varaible name
  188. was first used:
  189.  
  190.    Unused Shared / Global Variables
  191.    --------------------------------
  192.  
  193.     This error occurs for variables that are defined as Shared, or
  194.     Global, and then not used anywhere in the program, either in
  195.         definitions or references.
  196.  
  197.  
  198.   Unreferenced Shared / Global Variables
  199.   --------------------------------------
  200.  
  201.     This error occurs for variables which are defined as Shared/Global,
  202.         and have a value assigned to them at some point in the program, but
  203.     are never refered to in the arguments of a command or function.
  204.  
  205.  
  206.   Undefined Shared / Global Variables
  207.   -----------------------------------
  208.    
  209.     This error occurs for variables that are defined as Shared/Global,
  210.         and are referenced, but never have a value assigned to them anywhere
  211.         in the program.
  212.  
  213.  
  214.  
  215.  
  216. CAVATS 
  217. ======
  218.  
  219.  - Arrays are not checked, as AMOS requires that all arrays are 
  220.    dimensioned, before use, and produces an error if you try to
  221.    refer to an undimensioned array. However, the index parameters
  222.    are checked for references to other variables.
  223.  
  224.  - The arguments of Goto/Gosub statments are not checked for variable
  225.    references, as there is no way to distinguish them from label
  226.    references. The first expression of On <exp> Goto etc. statements
  227.    is checked properly.
  228.  
  229.  - Commands names that have several words, the last of which is a single
  230.    letter, and have no arguments may be mis-interpreted as shorter
  231.    command names with 1 - letter variables as arguements e.g. An example
  232.    is the AMOS Turbo Plus command 'Scene X'. This program would interpret
  233.    that as the command 'Scene', followed by a reference to the variable 'X',
  234.    and produce an error if 'X' is not defined. The program knows about a few
  235.    commands such as 'Scene X' and ignores them. If you find any others, 
  236.    please E-Mail me.
  237.  
  238.  - Def Fn statements are not checked for references, as they are not
  239.    interpreted at the point they are defined.
  240.  
  241.  - You might have to modify the MXVARS & Variable buffer size in the 
  242.    accessory if your program uses a lot of variables, and the accessory 
  243.    crashes.
  244.  
  245.  - Procedures